17 Bit Software 3: The Continuation/17-Bit_The_Continuation_Disc.iso/amigan/amigan 16/conman1.1/conman.doc

Text File | 1994-01-27 | 18KB | 358 lines

========================================================================
                              ConMan V1.1
                Copyright (c) 1987, 1988 by William S. Hawes
========================================================================

ConMan is a replacement console handler that provides line editing and
command history for any program that uses CON: windows.  It runs under
AmigaDOS V1.2 and is completely transparent to other software.  After
ConMan has been activated, all CON: windows opened by AmigaDOS will
automatically use the ConMan handler.  This includes command windows
opened by NEWCLI as well as any data input/output windows that your
program may use.

Version 1.1 offers several new features including command searching,
word-delete keys, an "undo" buffer, a utility to preload or save the
history buffer, and a command to select a keymap.  The most surprising
new feature, though, is an old feature --- ConMan is still shareware!
You've probably noticed that a number of popular shareware programs have
"gone commercial" and demand payment in advance; ConMan won't join these,
although my future products will be commercial until there is greater
public awareness towards shareware.


                        ----- Line Editing -----
ConMan allows you to edit the active (command) line using the left- and
right-arrow keys for cursor positioning.  The shifted left-arrow key
skips to the beginning of the current or previous word, and the shifted
right-arrow key skips to the start of the next word.

ConMan supports both insert and overstrike editing modes.  The CTRL-A key
toggles between the two modes, and the CTRL-^ key unconditionally selects
insert mode.  The default input mode is insert, but you can set the global
-o flag to select overstrike mode.  The input mode normally reverts to the
default mode each time you press RETURN, but the global -s ("sticky") flag
will cause the mode to remain set until you change it explicitly.

You can select the preferred input mode when you first install ConMan,
and can change it at any time using the SetCMan command utility.  Try
experimenting to see which input mode you like best, but note that these
are global flags and therefore apply to ALL ConMan windows.  Refer to
the paragraph on installation for a list of the global option flags.

There are several keys that can be used to delete characters, words, or
the entire line.  The DEL key deletes the character under the cursor,
and the BACKSPACE key deletes the character to the left of the cursor.
CTRL-Y deletes from the cursor position to the end of the line, and
CTRL-U deletes from the cursor to the start of the line.  CTRL-X deletes
the entire line, in keeping with the default CON: device.

Function keys F7 and F8 can be used to delete words in the backwards and
forwards direction, respectively.  They work just like the shifted left-
and right-arrow keys except that the characters are deleted.

CTRL-Z deletes both the current line and any lines that have been typed
ahead (but not yet read); this is very handy if you want to completely
abandon all typed-ahead lines.  CTRL-R provides a less drastic recall
by posting the typed-ahead lines back to the command line.

The Undo Buffer.
If you're editing a line and accidentally hit the up- or down-arrow key,
all is not lost.  Just press the CTRL-- (control-minus) key and the
former line will be posted back to the active line.  Only lines that
have been changed are added to the undo buffer.

Flow Control.
CTRL-S and CTRL-Q have been implemented to hold and release the screen
output, respectively.  While the CTRL-S action is not strictly necessary,
since entering any character will halt output to the screen, it is a
standard control option.  CTRL-W clears the entire window and refreshes
the active line.

End-of-File.
One other control character is recognized:  CTRL-\ sends an end-of-file
(a zero-length block) to the task reading from the handler.

All characters not explicitly required for editing purposes are passed on
to the command line.  In order to provide a consistent display, characters
that might cause interference with the display (like CTRL-L) are displayed
as a caret (^) followed by the uppercase alphabetic character.  Version
1.1 now supports the CTRL-N (shift-in) and CTRL-O (shift-out) characters.
Miscellaneous non-printable characters are displayed as a hash mark.


                       ----- Command History -----
ConMan "remembers" the commands that you type and lets you recall them
sequentially using the up- and down-arrow keys.  If you go past the line
you want, the down-arrow key will retrieve the next (more recent) line.
The shifted up-arrow key recalls the oldest line, and shifted down-arrow
recalls the most recent line.  The CTRL-B key will clear the buffer.

The history buffer is organized as a fixed-length memory pool with a
default length of 488 bytes.  New lines are inserted at one end, and
the oldest lines are "pushed off" the other end to make room.  The number
of lines that can be saved depends on their lengths, but is generally in
the range of 25 to 30.  The default size can be changed when you install
ConMan by using the -b option followed by the desired size in bytes.
For example, the command "conman -c -b1000" installs ConMan with a
1000-byte history buffer.

ConMan maintains the history in one of two modes.  In the default mode,
recalled lines are not re-entered into the history buffer unless the
line was "touched," and the history index pointer is left positioned at
the retrieved line.  This mode is convenient if you often go back into
the buffer to retrieve sequences of commands.

In "true history" mode, every line is re-entered into the history buffer,
even if it hasn't been modified after being recalled.  The history pointer
is always reset (to the most recent line) whenever a line is added to the
buffer.  The history mode can be selected when ConMan is installed or
by using the SetCMan utility.

If you prefer to regard the history buffer as a circular buffer rather
than a stack, try setting the -wrap option with ConMan or SetCMan.  The
index will "wrap-around" when it hits the top or bottom of the stack.

Release V1.1 of ConMan includes a command called "History" that will save,
load, or display the history buffer.  Refer to the "history.doc" file for
more information.


                         ----- Function Keys -----
There are several additional editing functions and window control features
that use the function keys.

Key F1 shrinks ("iconifies") the window to its minimum size, and F2 "zooms"
the window to its maximum size (usually the entire screen.)  Both keys act
as "toggles," and shrunken windows may be zoomed (and vice-versa.)  If the
window was opened without a sizing gadget, neither F1 or F2 will have any
effect.

Keys F5 and F6 are used to search for commands.  If you type a partial
command line and then press F6, ConMan searches in the up-arrow direction
for a line matching up to the cursor position.  You can move the cursor
to the right to constrain the search.  Key F5 works similarly in the
down-arrow direction.

Keys F7 and F8 delete words in the backwards and forwards direction.
They operate just like the shifted left- and right-arrow keys except that
the words are deleted rather than just skipped over.

Function key F9 moves the screen to the front or back of the display,
and F10 moves the window to the front or back.  Both keys act as "toggles"
provided that you don't deactivate the window or screen.  These keys are
useful when you're working with multiple windows or screens and need to
peek at the one in back.


                     ----- Window Definitions -----
ConMan accepts the standard AmigaDOS window specifications.  For example,
"CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
beginning in position (160,50).  The numeric parameters are truncated
against the maximum screen size, so a larger-than-normal window may be
safely specified (for those of you using "morerows").  The default size
is the full screen width and height.  ConMan sets the minimum window size
to allow room for the close gadget and depth gadgets.

Various Intuition options and gadgets can be selected by including a list
of attributes after the window title.  Here's how it works:  put another
slash ("/") after the window title, and follow it with any of the
attribute options listed below.

   Option Character                 Default Value
   ----------------                 -------------
   A <==> Activate                  Activated
   B <==> BackDrop                  Not a backdrop
   C <==> Close gadget              No close gadget
   D <==> Depth gadgets             Depth gadgets
   M <==> Move (drag) gadget        Drag gadget
   N <==> NoBorder                  Border (sorry, "B" was used)
   R <==> Refresh (SMART/SIMPLE)    Smart refresh
   S <==> Sizing gadget             Sizing gadget
   Z <==> Zero-Zero                 Not a GZZ

Each option character serves to TOGGLE the corresponding window attribute,
so if you include an option twice, it will cancel the effect.  The closing
slash is optional.  My apologies to those who wanted a slash in the title.

Examples: CON:10/10/300/100/Behind/nb/   a borderless backdrop window.
          CON:10/10/300/100/Fixed/acm    a nonactivated window, with a
                                         close gadget, that won't budge.


                         ----- Installation ----
To install ConMan you will need to copy a few files to your system disk,
but don't worry --- they're all small.  Install the file "Conhandler"
(184 bytes) in your L: directory, to keep those bigger handlers company.
Then copy the file "conhandler.library" (6152 bytes) into your LIBS:
directory.  Now copy the commands ConMan, SetCMan, and History to your
C: directory; the other command programs are optional.  The included
"ExecuteMe" file will handle the installation for you if you'd rather do
it automatically.  If you received ConMan in the form of an ARCed file,
first deARC it and then be sure to rename "conlib.lib" and "chandler",
or use the provided "ARCInstall" script to copy the files.

Once these files have been installed, issue the command "conman -c" to
activate the handler.  You should only run ConMan once, as it allocates
20 bytes of memory for the handler name string which won't be released.
After you've activated ConMan, open a window using NEWCLI and check to
to make sure that the new window has line editing and command history.
Once every thing is working properly, you should place the "conman -c"
command in your startup-sequence so that it's always available.

NOTE:  ConMan affects only those windows opened AFTER you activate it!
It would be very impolite indeed to pull the old handler out from under
the existing windows.

You can specify several command line arguments with the ConMan command:

   Code     Action
   ------   ------
   -bNNNN   select buffer size NNNN bytes
   -c       install as CON: (the default)
   -o       select overstrike mode
   -r       install as RAW:
   -s       select "sticky" mode
   -t       maintain "true history"
   -w       select "wrap-around" history

These command options can appear in any order and remain in effect until
you reboot the computer.  The -q option used in previous releases is now
obsolete, as ConMan writes its copyright to standard output by default.

A separate utility program called "SetCMan" has been provided to modify
or display the global options.  You can use SetCMan to change the -o,
-s, -t, or -w options at any time.
Examples: setcman ?
          setcman -o -s -t

If you usually operate from WorkBench and only occasionally need a CLI,
you can activate ConMan by using the icons.  First double-click on the
"LoadLib" icon to load the conhandler library, and then activate ConMan
by double-clicking the "ConMan" icon.  The next CLI you open should now
have the line editing and command history provided by ConMan.


                         ----- Distribution -----
This program is distributed as shareware (user-supported software) to
Amigoid life-forms everywhere!  Make sure your friends get a copy.
Your contributions are greatly appreciated and will help me maintain
ConMan as well as develop new products.  Send all correspondence to:

      William S. Hawes
      P.O. Box 308
      Maynard, MA 01754
      [phone]

My network addresses are BIX: whawes, PLINK: whawes, and CIS: 72230,267.

The suggested contribution is $10 (based on an earlier survey), but any
amount is welcome.  Fewer than 200 people have contributed in the year
since ConMan was first released.  Although this is actually good by
shareware standards, it wouldn't suffice to buy even one full-page ad
in (for example) AmigaWorld.

Commercial vendors are welcome to include ConMan with their products,
provided that it's noted as being shareware and that the documentation
accompanies the software.


                       ----- Other Products -----
I have a couple of other products available commercially.   ARexx and
WShell can be found at better dealers**, or you can order them directly
from me at the above address.

ARexx is a multitasking implementation of the REXX language, a high-level
interpreted language designed for macro-processing.  ARexx can be used
as the macro language for any software package that includes an ARexx
interface.  ............................ Only $49.95 (plus $2.00 shipping)

WShell is a fully-compatible CLI replacement with aliases, built-in and
resident commands, concurrent piping (as in pgm1 | pgm2 | ... | pgmN),
extended prompt/window titlebar fields, transparent support for REXX
macro programs, and a number of other features.  Isn't it time you put
some mussel in your command environment?  Just 50 clams (+ $2.00 shipping)

** better dealers are those that stock ARexx and WShell.


                         ----- Further Notes -----
ConMan also accepts input specifications in the form "CON:w20480",
where the hex digits following the "w" are the absolute address of an
Intuition window pointer.  This allows you to attach a console handler
to an existing window in a multitasking-safe way (unlike the methods that
require setting a field in the DOS device list).  If you're writing in C,
you could use the following sequence to open a window and attach a DOS
console to it:

      window = OpenWindow(&newwindow);   /* get a window          */
      sprintf(buffer,"CON:W%x",window);  /* build the name string */
      file  = Open(buffer,MODE_OLDFILE); /* open a console stream */

You can open a console window on a custom screen by including the hex
address of the screen in the specification string, as in
               "CON:S123abc/10/10/300/100/MyWindow."

Other Names.
ConMan answers to several names in addition to "CON:".  You can define it
as the "CNC:" device by appending the included "mountlist" file to your
DEVS:mountlist and then issuing the command "mount CNC:".  The CNC: device
can then be used just like a CON: window.  This allows the CON: definition
to be left intact, in case there are any incompatibilities between ConMan
and your existing software (but please let me know of any problems!)

ConMan is also a pipe-handler responding to the name PIP:NNNN, where
NNNN is the "capacity" of the pipe.  It must be opened using a private
packet called ACTION_DOUBLE (value 2000L); the filehandle you get from
a call to Open() counts for two and so can be cloned by your program.
My WShell command shell uses the ConMan PIP: device as the pipe handler.

Keymapping.
ConMan supports the Amiga's keymapping facility, which allows you to
reassign the editing functions to the keys of your choice.  To do this,
you must first construct a keymap either in assembly language or with
the help of a keymap editor.  You can then load the keymap using the
SetMap program on your WorkBench disk.  By default SetMap makes a keymap
global; if you want to use a special keymap from just one CLI, you can
use the included KeyMap command to define the desired map.  KeyMap with
no arguments will display a list of the available keymaps.


                         ----- What Next? -----
Several additional features will be added in the next release of ConMan.
A number of people have requested an option to have the handler not
display typed-ahead lines, so that the running program can write freely
to the screen and lines will be displayed only as they are read.  Also
in the works is support for an improved "iconify" state, so that the
window can be double-clicked to bring it back up to the former size.

I'm planning to release a ROM version of ConMan as soon as the hardware
vendors start including decoded ROM sockets on their boards.  If you're
interested in ROM-based software, drop me a note (or write directly to
the hardware companies).


                             ----- Bugs -----
All known bugs have been fixed in this release, so you should find it to
be very reliable.  If you do find a problem, PLEASE report it so I can
fix it!

There is a warning with regard to the "shrink" and "zoom" keys:  rapid
toggling between window states will crash the machine.  The problem
appears to be an interaction between Intuition and the console device
and will probably get fixed when Commodore upgrades the console device
in version 1.4.  Until then, take it easy with the F1/F2 keys.

An additional warning: the console device exhibits serious problems with
windows below some minimum size.  Opening windows of certain sizes
(e.g. con:0/0/10/20/) may cause the machine to crash, whether or not
ConMan is active.  For these reasons, I strongly urge you avoid console
windows smaller than 60X25 or so.


                       ----- Acknowledgements -----
Special thanks to John Toebes and the Software Distillery for all the
great suggestions, and to the contributors who helped make V1.1 possible.

                                    WSH (03/07/88)